Node / meshtastic / Meshtastic-Android / files / .specify / extensions / optimize / README.md

Displaying Rendered • View raw • Download

Audits and optimizes AI governance documents for context efficiency. Designed for long-term AI-driven development where constitutions grow organically and accumulate token debt.

In AI-driven development, the constitution is loaded into every AI session's context window. Over time:

• Token bloat: Rules, examples, and version history accumulate — costing tokens on every invocation

• Rule decay: Incident-specific rules persist forever because AI has no institutional memory

• Non-deterministic governance: Ambiguous rules cause different AI sessions to behave differently

• Governance echoes: The same rule gets restated across multiple files, wasting tokens and risking contradictions

• No learning loop: AI sessions make the same mistakes repeatedly with no mechanism to capture learnings

This extension provides tooling to detect and fix these problems.

T282828

specify extension add optimize

T8b949e# From a direct URL

specify extension add optimize --from https://github.com/sakitA/spec-kit-optimize/archive/refs/tags/v1.0.0.zip

T8b949e# For local development

specify extension add --dev /path/to/spec-kit-optimize

Analyzes the constitution across 6 categories uniquely relevant to AI-driven development:

1. Token Budget Analysis — measures per-section token cost and governance density

2. Rule Health Analysis — detects stale, incident-specific, superseded, and graduated rules

3. AI Interpretability Analysis — finds ambiguity, contradictions, unenforceable rules

4. Semantic Compression — identifies collapsible rule clusters, redundant examples, inline-to-reference conversions

5. Constitution Coherence — evaluates principle balance, rule scatter, cross-references, CLAUDE.md drift

6. Governance Echo Detection — finds cross-file duplication and total governance token budget

T282828

/speckit.optimize.run

T8b949e# Single category

/speckit.optimize.run --category token_budget

T8b949e# Report only (no apply step)

/speckit.optimize.run --report-only

Measures the token footprint of all governance files and extension commands. Tracks trends over time.

T282828

/speckit.optimize.tokens

T8b949e# Compare against previous report

/speckit.optimize.tokens --diff

T8b949e# Extensions only (skip governance files)

/speckit.optimize.tokens --extensions-only

End-of-session analysis: detects AI mistake patterns, repetitive corrections, and governance gaps. Suggests constitution rules or memory entries to prevent recurrence.

T282828

/speckit.optimize.learn

T8b949e# Rules only (no memory suggestions)

/speckit.optimize.learn --rules-only

T8b949e# Analyze from a specific commit

/speckit.optimize.learn --since abc1234

Suggest-only by default. Every command produces a report first. Nothing is modified until the user explicitly approves. The flow is always: Analyze → Report → Propose → User Consent → Apply.

Spec-kit standard paths. The extension works with any spec-kit project. It uses T383838.specify/memory/constitution.md as the primary constitution path and follows redirects for project-specific layouts. It never hardcodes project-specific paths.

Semantic preservation. Optimization removes redundancy in expression, not in intent. Every governance rule survives compression — only its token cost changes.

Copy T383838config-template.yml to T383838optimize-config.yml in the extension directory:

T282828

.specify/extensions/optimize/optimize-config.yml

Key settings:

• T383838categories.* — toggle individual analysis categories on/off

• T383838thresholds.max_constitution_tokens — flag constitutions exceeding this token estimate

• T383838thresholds.governance_budget_percent — max % of context window for governance overhead

• T383838target_context_window — context window size for budget calculations (default: 200K)

• T383838learn.min_corrections_to_flag — minimum repeated corrections before flagging a pattern

• T383838/speckit.constitution — authoring tool. Optimize hands off to it for applying approved changes with proper version bumping.

• T383838/speckit.analyze — consistency checker. Run after optimization to verify cross-artifact alignment.

• T383838/speckit.optimize.tokens → T383838/speckit.optimize.run — if token tracker reveals high governance overhead, run the full audit.

• T383838/speckit.optimize.learn → T383838/speckit.constitution — approved rules from session learning are applied via the constitution skill.

Reports are saved to T383838.specify/optimize/ (with user consent):

• T383838token-report.md — latest token usage snapshot (enables historical trends)

• T383838learning-report-<date>.md — per-session learning analysis

• Spec-Kit >= 0.1.0

• An existing populated constitution (not a raw template)

• Git repository (for learn command's session analysis)

MIT